Skip to main content

Managing API Keys for Secure Access

API access is authenticated using API keys. Every API call must include the following keys in the request:

  • App Key: Represents the organization associated with the key.
  • Secret Key: A unique, private key generated for secure access. This key should never be shared.

Overview of App and Secret Keys​

App Keys:​

  • App keys are generated once per organization and cannot be regenerated or cycled.
  • These keys uniquely identify your organization.

Secret Keys:​

  • Secret keys are specific to the privileges and access requirements defined for the organization or sub-organization.
  • They are generated only once and must be stored securely, as they cannot be retrieved later.

Steps to Generate an API Key​

Step 1: Create an Organization or Sub-Organization​

To begin, create an organization or a sub-organization using the following API call:

curl --location 'http://localhost:8080/v1/organisations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <JWT_TOKEN>' \
--data-raw '{
    "name": "ABC Holdings",
    "type": "computer_services",
    "company_registered_date": "2020-11-01",
    "address": "34 Webings Road",
    "email": "hello@abc.com",
    "phone": "1238129038290",
    "country_code": "ae",
    "parent_organisation_id": "2Uhi9mFkXpLIleNbAzbxlTMJDHm"
}'

Step 2: Define Access Privileges​

Specify the required access privileges for the organization or sub-organization by generating a secret key. Use the following API call:

curl --location 'http://localhost:8080/v1/organisations/<ORGANISATION_ID>/secret-keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <JWT_TOKEN>' \
--data '{
    "name": "dev key 6",
    "permissions": {
        "partners": "read_write",
        "payments": "read_write",
        "users": "read_write",
        "reports": "read_write"
    }
}'

Step 3: Generate the API Key​

Once the secret key is created, save it securely. API keys are generated only once and cannot be retrieved again. Store them in a secure environment, such as a key management system.

Access Control Using ACL Backed by Casbin​

This API system uses Access Control Lists (ACL) for managing key permissions, implemented with the Casbin library. ACL offers a fine-grained access control model, allowing each API key to have its own set of specific permissions. This approach is more flexible than traditional RBAC (Role-Based Access Control), where permissions are grouped into predefined roles.

How ACL Works:​

  • Custom Permissions: Each secret key is assigned individual permissions directly, such as read, write, or read_write access for different resources.
  • Granular Access: Permissions can be tailored to the exact needs of each key, ensuring precise control.
  • Flexibility: Unlike RBAC, which ties users to roles, ACL allows each key to independently manage its access rights.

Why Casbin?​

  • Casbin is a powerful and efficient open-source library for access control, providing policy enforcement for API calls.
  • It supports various access control models, including ACL, and integrates seamlessly with modern applications.
  • With Casbin, policies can be dynamically configured, making it ideal for applications requiring customizable access control.

Advantages of ACL over RBAC:​

  • Granularity: ACL enables specific rights per key, whereas RBAC applies the same rights across all users of a role.
  • Independence: Permissions are not tied to roles, reducing complexity and enhancing flexibility.

For more information on Casbin, visit Casbin.org.

Using the API Key​

To make an authenticated API call, include the secret key in the Authorization header of your request.

Example: Payment Creation​

curl --location 'http://localhost:3000/v1/payments' \
--header 'idempotency-key: 7af0dd2e-5596-4f6e-84e8-89c4ebb75d8c' \
--header 'Content-Type: application/json' \
--header 'Authorization: <SECRET_KEY>' \
--data '{
    "payment_method_code": "sg_dummy_banktransfer",
    "currency": "sgd",
    "amount": 100,
    "details": {
        "banktransfer": {}
    }
}'

Security Best Practices​

  1. Secure Storage: Use secure systems like AWS Secrets Manager or HashiCorp Vault for storing API keys.
  2. Least Privilege: Assign only the permissions necessary for the application’s function.
  3. Key Rotation: Regularly review and regenerate keys where feasible. While App Keys cannot be cycled, new secret keys with updated permissions can be created as needed.
  4. Audit Access: Monitor and audit API usage to detect and prevent unauthorized access.